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Abstract ~ 

Whlstter adds support for Snapshots to the Microsoft® Windows® XP operating system. This White 
Paper describes the design Issues involved for hardware vendors who wish to add a Snapshot 
Provider Into this Infrastructure. 

Note that there are substantial changes from the provider white paper documentation provided at 
Whistler Beta l. 
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INTRODUCTION 



J- 



Definition Of Terms 



Auto-Release 



Copy-on-write 



Deleted Snapshot 



Exposed Snapshot 



GUID 



A snapshot that is deleted immediately after the 
Requestor exit or detach, Ucal (non-SAN) backup 
software snapshots are auto-release. 

A snapshot created by saving only the differences to 
the original volume. See snapshot data. 

Deleted snapshots are not accessible at all and must 
not be made accessible at any time in the future. 
Deleted snapshots may still occupy resources (for 
example space in a software storage File.) 

Accessible In the Windows name space via drive 
letter, mount point r and/or network share. 

Many of the ID numbers used in VSS, (and in many of 
Microsoft's technologies) are GUIDs - Globally Unique 
identifiers. The CoCreateGuldO function creates a 
GUID, a globally unique 12fl-bit Integer. Use the 
CoCreateGuidO function whenever an absolutely 
unique persistent Identifier In a distributed 
environment is needed. To a very high degree of 
certainty, this function returns a unique value - no 
other Invocation, on the same or any other system 
(networked or not) should ever return the same 
value, 

GUIDs should not be re-used. They are Intended to 
be unique identifiers. 



Hardware Snapshot Hardware providers consist of a user*mode 
Provider component that works In conjunction with a hardware 

storage adapter or external RAID storage subsystem. 
I/Os are Intercepted by the hardware (not software) 
which Instantiates a snapshot LUN, 

Hidden Snapshot Not accessible in the Windows name space. Accessed 
only via //7/GLOBALROOT or otherwise masked. 

Legacy Application An application that does not Include a writer and does 
not observe the snapshot synchronization protocol. 

Managed Snapshot A snapshot that can be queried via VSS, In particular, 
the original volume, snapshot set and snapshot set 
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Multi-layer 
Snapshot 



membership can be determined. 

More than one snapshot exists for a specific original 
volume. 



Original Volume The volume from which a snapshot Is derived. 

Persistent Snapshot Existing beyond a dean shutdown or hard crash or the 
operating system. 



Plex 

Requestor 

Snapshot 
Snapshot Data 



A snapshot Initially created by mirroring. This special 
case of snapshot data that represents a snapshot 
without the need for the original volume data. 

A process that requests that one or more snapshot 
sets be taken of one or more original volumes. A 
backup application is a good example, 

A read-only point-ln-time replica of original volume 
state. Each snapshot is keyed by a persistent GUID. 

A set of deltas and configuration Information which 
when applied to the original volume, comprise a 
snapshot. 



Snapshot Provider A software snapshot provider or a hardware snapshot 
provider. Providers own the snapshot data and 
instantiate the snapshot. 

Snapshot Set A set of snapshots with a common SnapShotSet 

Identifier. Snapshot Sets are a collection of snapshots 
that were created at the same time. This Is keyed by 
a persistent GUID. 

Snapshot Storage Resources consumed by a software copy-on-wrlte 
software provider 

Snapshot Storage A volume that holds snapshot storage files for a copy- 
Volume on-write software provider 

Software Snapshot Software providers are implemented as a user-mode 
Provider component plus a kernel-mode driver. l/Os are 

Intercepted by the driver that Instantiates snapshot 
volumes. The driver may be a ^storage filter driver or 
a component of a volume manager. 

Transporting Moving a managed persistent snapshot between 

hosts; this usually occurs on a SAN. 
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Volume Name A Win32 definition - the name of a volume in the 

\\?\Volume{G<//D>\ syntax that was introduced In 
Windows 2000, 

The Windows service that coordinates requestors, 
providers, and writers- The Volume Snapshot Service 
Is abbreviated as VSS. 

Any application that stores persistent information on 
one or more volumes, and which participates In 
snapshot synchronization. Typically this might be a 
database (e.g, SQL Server) or system service (e.g. 
Certificate Server). 



Volume Snapshot 
Service 



Overview 



An overview of the Volume Snapshot Service (VS5) and its cooperating 
components is shown on the page following. Summarize the roles: 

• Providers own the snapshot data and instantiate the snapshots. 

• Writers are applications that are changing data and participate in the 
snapshot synchronization process. 

• Requestors Initiate the creation and destruction of snapshots. Our design 
is focused on the scenario where the Requestor is a backup application. 

• VSS provides coordination between these parties. 

In addition, there Is spedal support In the Windows file systems flush and hold 
filesystem data at a common polnt-in-tlme across multiple volumes for a 
snapshot set. This support Is known as 'Lovelace', and Is collectively implemented 
by a number of components Including VSS, NTFS, and the native volume 
snapshot driver volsnap.sys. 
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The Snapshot Provider 

Types of Providers 

Hardware providers Implement the IVssPiroviderCreateSnapshotSet and 
lVssHardwareSnapshotP>rovider Interfaces. The first interface is common to all 
providers and implements the snapshot state sequencing. The second interface is 
specific to hardware providers and operates on a LUN abstraction. 

Providers are Implemented as COM components and called out-of-proc by vss. 
Providers use provider-specific mechanisms to communicate with the host 
adapter or external RAID storage subsystem that Instantiates the snapshot LUNs, 
There should be no need for any extra kernel mode component 

Hardware providers operate on LUNs. VSS performs all mappings from original 
volumes to UJNs f aU work to hide or expose snapshots, and orchestrates read- 
only or read-write access to the snapshot data. 



Hardware providers register as VSS_PRQV_HARDWARE as defined In vss.idl: 



*XP*4*£ eiaxm VSS PJVOVIDSR TYPE 

VSS_P*0VJBNKHOW1I _ q # 

VSS_FROV"sTSTEK m j/ 

VSs"pROV^SOP«ttRra: _ 2 ' 

The system provider is the native volsnap^ys snapshot driver. No other providers 
should register as VSS_PROV_SYSTEM. No provider should register as 
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/ 

VSS_PROV_UNKNOWN. 



Provider Registration and DeRe^istration 

Only VSS calls providers. The provider registers for calls by Invoking 
lVssAdmin2:RegisterProvid€r()- Once registered, the provider will be involved in 
snapshot management until dereglstratlon via lVssAdmln::UnRegisterProvlder(). 



Snapshot Provider Load and Unload 

Providers can be frequently loaded and unloaded. Providers can provide an 
optional notification interface iVssProvlderNotm cations that can be used to detect 
these Situations. Providers only need to implement this Interface If It is useful for 
them to catch these events. 



The Snapshot Creation Process 



The diagram on the following page shows a non-error representation of the 
message flow between the various parties in the course of creating a snapshot 
from the perspective of a requestor. 

A requestor is the application that Initiates the request to create the snapshot It 
is typically a backup application, VSS in turn calls the provider when necessary. 
From the provider's perspective, the requester makes three important requests: 

1. The requestor begins the snapshot creation activity by calling 
StartSnapshotSetO- VSS implements this function, and the main effect is 
to generate a new GUID that will be used to Identify the snapshot set - 
the SnapshotSetld. The provider is not Involved In this step, but the 
SnapshotSetld is used extensively In all the subsequent steps. 

2. For each volume it wishes to snapshot In this set, the requestor calls 
AddToSnapshotSetQ, VSS determines which provider will be used to 
snapshot the volume, VSS gives preference to hardware providers, then 
software providers, and finally the system provider. 

• The same provider need not be used for all volumes In a specific 
snapshot set. 

• For a hardware provider to be selected, the hardware provider must 
be able to support all LUNs contributing to the specified volume. 

• The first provider (hardware, software, or system) that accepts the 
offer to snapshot the volume will be the provider for that volume. 

• There Is no guarantee on the order in which hardware providers are 
called. 

3. After one or more calls to AddSnapshotSetQ, the requestor can aslc for 
the snapshot to be created using the DoSnapshotSetQ function. VSS 
then communicates with a number of system elements In order to create 
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the snapshot. The DoSnapshotSet() function performs this work 
asynchronously, and the requestor can either poll or wait for the 
snapshot creation process to complete 

When the process is complete, the requester can query the SnapshotSet to 
determine if it was successful, and If not, can determine which elements failed. 



It is a key goal to minimize the time Interval between freeze and thaw of the 
writer applications. As such, every provider must also have the same goal. 
Providers must asynchronously start all preparation work related to the snapshot 
in the BeglnPrepareSnapshotQ function,, and then await its completion in the 
EndPrepareSnapshot() function. A hardware provider that used plexes could start 
the sync process no later than BeginPrepareSnapshot{) and await It's completion 
In EndPrepareSnapshot()« 
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a 



Overview of Snapshot Creation Processing 
Requestor VSS Provider 

StartSnap5hotSetO 



AddToS naps hot SotQ 



DoSnapsnotSelQ 



..and wait for 
asynchronous 
completion of 
DoSnapshotSetO— 



Offerthis volume to each 
Provider in turn 



..(Success) 



BeglnP repareSnapshotQ , 



_(5uccass) 



EndPrepareSnapshotO 
.called for eac h provider 



PreCommftSnapshoiO 
. called for each provider 



CommitSnapshcteO 
called for each provider 



PostCommJlSnap&hotsO 
catted for each provider 



4r 



Lovelace 



Writer 



Flush and Hold VQ 



VO 



J3J2WCL 



Figure 1. Snapshot Processing overview 
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Note that the snapshot set is fixed at the Invocation of DoSnapshotSet. New 
volumes cannot be added later; the additional volumes could not have the same 
polnt-ln-tlme. 

There is a limit of 64 volumes in the snapshot set. A specific volume may map to 
an entire LUN r a portion of a LUN, entire LUNs, or portions of multiple LUNs. Most 
configurations will have one volume per LUN, although arbitrary mappings are 
possible. 

There is no limit on the number of snapshot sets or the number of snapshots of 
an original volume, A provider may define specific limits or dynamically limit 
based on hardware resources available. 
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PoinHn-tfme for Legacy Writers 

VSS includes special OS kernel support that defines the point-in-time that is 
common for all volumes in a Snapshot Sec Hardware providers do not need to 
directly interface with these kernel technologies, since they are invoked as part of 
the normal snapshot commit processing. However, it is useful to understand the 
mechanisms involved since it explains the definition of 'pofnt-in-time' for Legacy 
Applications (applications that have not exposed a 'Writer' Interface). 

This kernel support for common point-ln-time is distributed between the 
volsnap.sys driver, the fiiesystems, and VSS. This support is collectively referred 
to as ^Lovelace' - a codeword that was used during the development of VSS. 

i) Before Lovelace is invoked, VSS has already: 

a) Determined which volumes are to be involved in the snapshot 

b) Determined which provider is to be used on each volume. 

c) Frozen the applications that are accepting freeze/thaw messages. 

d) Prepared the providers for the snapshot using PreCommltSnapshot All 
providers are just waiting to do the actual split. 



2) 



The point-in-trme is then created. VSS concurrently flushes the fllesystems on 
all the volumes that are to be snapshotted. 

a) VSS Issues a new IOCTT. that flushes the fllesystems. That IRP passed 
down the storage stack to volsnap,sys. Volsnap.sys then holds the non- 
pagefile write IRPs until step 4) below. Any legacy filesystem (such as 
RAW) without support for this new IOCTl passes the unknown IOCTL 
down - where it will Is again held by volsnap-sys. Note that on NTF5 
volumes, the flush also commies the NTFS log. 

b) This suspends all NTTS/FAT metadata activity; the filesystem metadata is 
cleanly committed. 

c) The snapshot Instant: Volsnap.sys next causes all subsequent non- 
pagefile write IRPs to be queued on all the volumes that are to be 
snapshotted. 

d) Volsnap.sys waits for all pending writes on the snapshot volumes to 
complete 1 . The volumes are now qulesced with respect to writes, and 
were qufesced at exactly the same moment on each. Note that there are 
no guarantees about writes to user mapped sections or writes Issued 
between (a) and (b) on filesystems that are do not Implement the flush 
IOCTL (e.g. RAW). 



dS^ lf many ,arge UOs are ***** °p <**p'y In the 
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3) VSS Instructs each provider in take the Snapshot; CommitSnapshotsO, The 
providers should have done all their preparation before so that this is a % flidc 
the switch' operation, 

4) VS5 releases all pending write IRPs (including the IRPs that were blocking the 
filesystems at the conclusion of their commit path) by invoking another new 
IOCTL passed to vol$nap.sys. 

5) if the snapshot process was successful, the VSS now: 

a) Issues PostCommltSnapshot to the providers 

b) Issues Thaw to the Writers 

c) Informs. the Requestor that the snapshot process has completed 



PreCommitSnapshotO, CommitSnapshotsO to PostCommitSnap&hotsO are all 
time critical. AH I/O from applications with writers is frozen from 
PreCommitSnapshotO to PostCommltSnapshotsQ; delays affect application 
availability. All file I/O, including Legacy Application I/O, Is suspended during 
CommitSnapshotsO. 

Providers should do all time critical work should be completed prior to 
EndPrepareSnapshotO. 

• CommitSnapshotsO should be returned within a few seconds. Lovelace will 
cancel the lOCTLs that are holding the I/O if the subsequent release is not 
received within 10 seconds. VSS will fail the snapshot creation process. 

• The full sequence of PreCommitSnapshotO to the return of 
PostCommitSnapshotsO must complete within 30 seconds. 

During CommitSnapshotsO the provider must avoid any non-paging file I/O; such 
I/O has a very high probability or deadlock, in particular, the provider should not 
synchronously write any debug or trace logs. 
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HARDWARE PROVIDER Hardware providers may support copy-on-wrtte or pfex (full mirror copy) 

INTERACTIONS AND snapshots. Resource allocation for snapshots should be *automagic- - reasonable 

BEHAVIORS default behavior should occur if the requestor does nothing. The full support for 

plex resource allocation will be via the post-Whistler Virtual Disk Service. 

Software copy-on-write providers implement a common management Interface 

for snapshot storage files; a similar interface will be defined when desired by 

copy-on-wrlte hardware providers. 

Hardware providers associated with external SAM RAID subsystems should 
support transportable snapshots to allow movement between hosts on a SAN. The 
full support for this will Include the post-Whistler Virtual Disk Service and the 
Fabric Visualization service. Meanwhile, the provider assumes some of that 
functionality. 

Hardware providers can be stateless across boot epochs. Hardware providers 
running on multiple machines in a SAN yet managing the same RAID subsystem 
need not coordinate between providers on a SAN. The coordinator maintains any 
necessary state. Two kinds of state are recognized; 

* State necessary to support data access to the voiumes contained on a 
hardware snapshot This includes any tagging of a volume as read-only or 
hidden. This state must be on the hardware LUN and travel with the LUN. 
This state is preserved across boot epochs and/or device discovery. VSS 
manages this state. 

* State necessary to recognize a specific volume as part of a snapshot set. This 
state is persisted by VSS In conjunction with the Requestor that originally 
created the snapshot set, 



The Snapshot Creation Process 

Creating a snapshot set with a hardware provider proceeds as follows: 

1) As the requestor adds each volume to the snapshot set, VSS determines the 
associated LUNs. Physical device Identification information 
(VDS_J-UrUNF0RMA71ON) Is retrieved for each. 

2) The hardware provider uses the physical device Information to determine if 
the LUNs are supported. This determination must be all or nothing: the same 
hardware provider must support all LUNs contributing to a specific volume. 

3) For each supported LUN, the hardware provider augments VDS_LUN_lNFO 
with any additional information available such as Interconnect address. 

4) For each volume in the snapshot set, VSS lnvoke$ BeglnPrepareSnapshot 
with the same array of VDS_JJUN w ENFO. Within a single call, all LUNs in the 
array are unique, however the same LUN may reappear In a subsequent call 
whenever the same LUN contributes to multiple volumes. The provider must 
handle that case correctly. 

5) Prior to CommitSnapshots, the coordinator tags all affected LUNs, The tag 
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will cause all volumes on the affected disks to be surfaced on the receiving 
machine as read-only and hidden. 2 Note that the snapshot UUNs have not yet 
been separated from the original LJUNs; both the original LUNs and the soon- 
to-be-snapshot LUNs are written at this time. 

6) The tag is designed such that In the event of a system crash, the tagged original 
LUN will not be affected. That is, all volumes on ttie original (unbroken) LUN will 
be treated as normal - retaining whatever drive letter/mount points and 
read/write status. 

7) At ComrnitSnapshots, the snapshot LUNs are broken from the original LUNs. If at 
all possible, the snapshot LUNs should be masked at the storage subsystem and 
not simply discoverable by other hoses on the SAN. 

8) After CommitSnapshots, VS5 removes the tag on ail affected LUNs. Since the 
snapshot LUN has been broken from the original LUN, the snapshot LUN retains 
the read-only and hidden tags. 

9) After PostComrnltSnapshots, the Volume Snapshot Set retrieves an array of 
VDS_LUN_Inj=o for each newly created snapshot LUN. The provider must provide 
enough Information to allow the newly created snapshot LUN to be moved to 
another machine. Note that at this time, the snapshot LUN should be Inaccessible 
to this machine; the provider must use mechanism other than simply reading the 
information from the LUN. 

10) vss appends the following to the XML document describing the snapshot set: 

a) Tne original LUN VOS_LUN.JNFO array 

b) The new snapshot LUN vT>S_LUN_INFO array 

c) The disk extents for each volume in the snapshot set 

11) The new snapshot LUN VDS_I_UN _JNR> array Is passed to the hardware 
provider. The provider should unmask the LUN at the Storage subsystem and, 
If possible filter accesses to this machine. The provider should also perform 
any and all zoning necessary. The provider should not cause a bus rescan 
(IOCU^OISKLFINDJIEW.OeviCES). VSS will perform any necessary 
unmasking at the host and then cause the rescan to allow the LUNs to be 
discovered by Pnp and the volumes to come online. 

12) As new volumes are discovered, VSS uses the original LUN VDSJJUNJNFO 
ARRAY and the disk extents for each volume in the snapshot set to determine 
which new volume corresponds to which original volume. 

13) At this point, all volumes contained on the new snapshot LUNs are mounted 
hidden and read-only and VSS has a mapping from original volume to 
snapshot volume. 

Post Whistler, VSS will Invoke the Virtual Disk Service (and Implicitly the Fabric 
Virtualfeatlon Service) to locate, unmask, zone, and online each LUN In the 
snapshot set. This will be transparent to the provider- 



2 The tag Is Implemented using hidden sectors on MBR disks or operating system 
software specific bits In the partition header entry on GFT disks. 
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The volumes are created as read-only and hidden to minimize confusion. Because 
there is not a one-to-one mapping of volumes to LUNs, the set of snapshot LUNs 
may Inadvertently Include *extra- volumes. When the snapshot is surfaced, those 
volumes remain hidden from applications. 

After creation, a snapshot Set may be converted to read-write and/or exposed via 
a drive letter, mount paint, or share, 

Transporting Snapshots on n SAN 

Snapshot sets may be transported, moved between hosts, on a SAN. The sec may 
be transported one or many times after Initial creation. 

From the point of view of a provider capable of transporting LUNs between hosts, 
there Is little or no difference between a non-transportable and a transportable 
snapshot set. 

Transportable snapshot sets must be created with the TRANSPORTABLE context 
attribute- All volume In the set must be transportable. In step 2) above, the 
provider must not only support the LUIM, but also be able to transport it to accept 
the LUN. Creation of a transportable snapshot set concludes at step 10) above 
when VSS records the LUN Information In the XML document 

On the receiving machine, the requestor imports the snapshot set. This method 
uses the XML document describing the snapshot set as Input Importing proceeds 
by: 

1) VSS constructs an array of snapshot LUN VDS_LUN_INFO from the XML 
document. 

2) That array Is passed to the hardware provider. The provider should unmask 
and/or zone all LUNs, but need not cause a bus rescan 
(IOCTK_DISKJ^ND^NEW^DEVIC£S). VSS will perform any unmasking at the 
host and then cause the rescan to allow the LUNs to be discovered by PNP 
and the volumes to come online. 

3) As new volumes are discovered, VSS uses the original LUN VDSJ_UNjnfo 
ARRAY and the disk extents for each volume in the snapshot setto determine 
which new volume corresponds to which original volume. 

4) At this point, all volumes contained on the transported LUNs are mounted 
hidden and read-only and VSS has a mapping from original volume to 
snapshot volume. 

Note the similarities between steps 11 through 13 in the slnole machine case and 
steps 2 through 4 when transporting. 
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Required Behaviors 

A snapshot provider must have the following behavior to ensure requestor 
compatibility. At run time, a backup application or other requestor that uses 
snapshots can function correctly without any knowledge of specific provider 
implementation details. 

Automagic Resource Management 

It must be possible for the requestor simply to add a volume to a snapshot set. 
The provider must include an automatic rule for allocating drive space for the 
implied plex or copy-on-write snapshot LUN. in the absence of such a rule, the 
provider must never agree to support the volume. 

Plex providers may Include a provider-specific interface for resource 
management. That API Is only temporary; post-Whistler binding a plex to a LUN 
will be done via the Virtual Disk Service. 

The hardware provider must not include a provider-specific API for managing this. 
Software providers Implement a common management API; a common hardware 
provider API will be added when necessary. 

Create Snapshot Volumes as Road-only and Hidden 

VSS tags each volume on each affected LUN such that the resulting snapshot plex 
will be hidden and read-only when detected by a Whistler machine. Drive letters 
and/or mount points are not automatically assigned. 

Hardware providers need do nothing to comply with this requirement. 

Hardware Snapshots not Supported en Wo If pack 

Wolfpack cannot accommodate LUNs with duplicate signatures and partition 
layout. The snapshot LUNs must be transported to a host outside the cluster. 

Snapshots Containing Dynamic Disks must be Transported 

The native support for dynamic disks cannot accommodate LUNs with duplicate 
signatures and configuration database contents. The snapshot LUNs must be 
transported to a different host. VSS enforces this. 

When transporting dynamic disk LUNs to a new host, It Is best that at least one 
dynamic disk already exist on the receiving host. This ensures that the disk group 
identifiers will be unique to both machines. 

Garbage Collection of Non-Perststent Snapshots 

vss Is designed to automatically delete non-persistent snapshots when the 
requestor releases Its Interface; this Includes the case where that release Is the 
result of a crash of the requestor. The same garbage collection should occur In 
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the event of VSS crash or restart. 

This affects hardware providers In one and only one way: If a snapshot has been 
committed but the VDS_l_UN_INFO associated with the new snapshot LUN has not 
yet been passed to VSS, any data on that LUN must remain inaccessible. A pfex 
LUN may be resynchronlzed with the original LUN or simply treated as 
unallocated. Copy-on-wrlte space must be reclaimed. 

Providers are Out-of-Proc 

All providers must be Implemented as out-of-proc COM components. This is 
because mere is no performance reason to have them as in-proc components, 
and because this helps to Isolate the coordinator from implementation Issues in 
third-party providers. 

Time Critical Operations 

As noted previously, long operations such as syncing mirrors, should be initiated 
in BeglnPrepareSnapshotC). This function should return immediately, but perform 
the required preparation work asynchronously, 

EndPrepareSnapshotO serves as a 'rendezvous' function; the provider can wait 
synchronously in this method for completion of Che preparation work that was 
started by BeglnPrepareSnapshotQ. 

Providers must not add delays in PreComrnitSnapshotQ, CommltSnapshotQ, or 
PostCommitSnapshotO since applications are frozen at this time. 

Careful I/O during CommitSnapshote 

Hardware providers should not need to do any I/O to the affected volumes during 
CommitSnapshots. If any I/O is required, providers must take great care with any 
I/O issued to an original volume during the CommttSnapshotsQ function. 

During CommitSnapshots{) f VSS Is using the ^Lovelace' drivers to block I/O to the 
original volumes being snapshotted. If the provider uses synchronous file VO to a 
volume which Is in the snapshot, then that I/O will be blocked and the snapshot 
commit process will be deadlocked. The Lovelace timeout will break this deadlock 
after 10 seconds, but this will cause the snapshot to fall. Providers must not 
provoke such a deadlock and failure. If they do deadlock in this way they will be 
considered faulty and unsupportable. 

If I/O must be attempted, It must be performed asynchronously. The VO will not 
complete until after all providers have returned from their CommltSnapshots() 
method. In general. It Is better to perform such I/O In the later 
PostCommitSnapshotsO call. 

State Transitions 

The state model In a snapshot provider Is greatly simplified by the fact that 
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snapshot creation for a snapshot set Is serialized all the way from 
StartSnapshotSetQ through to the completion of DoSnapshotSet(). 

The following table lists the valid state transitions for a snapshot 



Table. Snapshot state transitions 



Initial State 


Operation 


Resultant state 


V^S_SS_UNKNOWN 


Enter 

BeginPrepareSnapshots() 


VSS^SS.PROCESSING.PREPARE 


VSS_SS_PROCESSING_PREPARE 


Leave 

Begi nPrepaneS napshats() 


VSS^SS^PREPARING 


V S 3JSS_P R EPARI NG 


Leave 

EndPrepareSnapshotsQ 


VSS_SS_PREPARED 


V$$J$S_PREPARED 


Enter 

PreCommitSnapshots{) 


VSS_S$_PROCESSIhiG_PRECOMMIT 


V5SJSS_PROCESSING_PRECOMMIT 


Leave 

PreCommitSnapshot&{) 


VSS_S5_PRECOMMfTED 


VSSJSS.PRECOMMFTED 


Enter CommitSnapshots(> 


VSS^SS^PROCESSINGjCOMMlT 


VSS_SS_PROCESSI NGjCOMMIT 


Leave 

CommitSnapshotsO 


VSS_SSCOMMrTED 


VSS_SSjCOMMlTED 


Enter 

PostCommilSnapshotsQ 


VSS_SS - PROCESSfNG_POSTCOMMir 


vssjss w PROCESSrNG_PosTCOMMrr 


Leave 

PostCommitSnapshotsO 


VSS_SS_CREATED 


Any 


AbortSnapshotsQ 


VSS_SS_ABORTED 



Error Handling 

VSS allows many snapshots to exist at once, but it only allows one snapshot set 
to be proceeding between StartSnapshotSet through DoCcmmitSnapshotO. 

No Partial Commit 

If any provider fails a snapshot on any volume or LUN In the snapshot set, then 
the creation of the entire snapshot set is aborted. There is no way to avoid this 
behavior- it is defined this way In order to simplify support and behavioral Issues 
associated with partial failure semantics. 

Reporting Fault Conditions 

In the event of any hardware provider error or fault condition, the provider 
must log an error to the system event log. This Includes, but Is not limited to, any 
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provider-specific error when creating or importing a Snapshot Set or resource 
allocation failure for copy-on-write snapshot after creation. 

Unsupported Scenarios 

Snapshot providers may only snapshot a volume if they are able to snapshot all 
LUNs contributing to the volume. Anything else would require a level of 
coordination between providers. Note that this specifically excludes the case 
where a volume has been grown by concatenation and exists partly on a LUN 
managed by hardware- based provider A, and partly on a LUN managed by 
hardware-based Provider B or when the volume is striped between such LUNs. 
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Introduction 

The Hardware Snapshot Provider interfaces are iVssAdmin, 
IVssProviderNotiflcatlons, iVssProvlderCreateSnapshotSet, and 
IVssHandwareSnapshotProvider. 

IVssAdmin 

The IVssAdmin interface is implemented by VSS f and manages the list of 
registered providers- 
Methods 
Name 

Query Providers 
Reg tsterProvider 
UnregisterProvider 

IVssProvidertiotificatton 

Snapshot providers can be frequently loaded and unloaded. To detect this, 
providers can provide an optional Notification Interface IVssProviderNotifi cations. 
Implementation is optional; providers only need to Implement this Interface if it Is 
useful for them to catch these events. 

The WssProviderNotifications interface Is implemented by the provider and Is 
used by VSS to notify the provfder about specific events. Every provider must 
support tnls Interface. This interface must be accessible using 
lVssHardwareSnapshotProviden:Queryinterface, 

Methods 

Description 

Called by VSS to notify the provider that 
it was Just loaded. 

Called by VSS to notify the provider that 
it will be unloaded. 

IVxsProviderCreateSnapshotSet 
The IVssProvlderCreateSnapshotSet interface contains the methods during 
snapshot creation. All providers must support this Interface; the Interface is 
common to software and hardware providers. 

Methods 
Name 

End P repareSnapshots 
PreCommitSnapshots 
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HARDWARE PROVIDER 
INTERFACES AND 
METHODS 



Description 

Queries all registered providers. 
Registers a new snapshot provider. 
Unregisters an existing provider. 



Name 
OnLoad 

OnUnload 



Description 

Ensure all LUNs in the snapshot set are 
prepared 

Ensure that the provider Is ready to 
OuirJciv commit rhfl nrenanxJ LUNs. This 
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CommitSnapshots 



PostCommitSnapshots 



AbortSnapshots 



happens immediately before the Flush- 
and-hold writes, but while applications 
are in their frozen states. 

Quickly commit all LUNs In this provider. 
Special restrictions exist on what 
operations the Provider may perform 
during this call. 

Called after all the snapshots have been 
committed. This happens immediately 
after the release-writes to the I/O 
subsystem, but while applications are in 
still In their frozen states. 

Ends the prepared snapshots in this 
provider. This includes all non-committed 
snapshots and any pre-committed ones. 



IVssHardwareSiiapsliQtProvider 

Each hardware provider must implement the IVssHardwareSnapshotProvider 
interface. The COM class that implements this interface is specified by the 
administrator in IVssAdmin::RegisterProvider at registration time. 



Methods 
Name 

AreLunsSupportcd 



BeginPrepareSnapshot 
GetTargetLuns 



Locate Urns 



OnLunEmpty 



Description 

Allows VSS to determine If this hardware 
provider can snapshot the LUNs that 
contribute to a specific original volume. 
The provider also updates the 
VDS_LUN_INFO structure. 

Adds LUNs to the snapshot set. 

Retrieves the hardware identification 
Information for each new created LUN 

Performs any necessary RAID subsystem 
unmasking and/or zoning to allow a 
snapshot LUN to be discovered by this 
machine. 

Notifies the provider tliat a lUN that 
previously contained snapshot no longer 
contains data of interest. 



I VssAdmiti: Registration of Snapshot Providers 

A provider registers with VSS via IVs^Admin:;ReglsterProvider(): 
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stdmeihOoikp rvuBAijain: :aagiae«sPxavidar< 



ZH 


VSS_ID 


ProvidarXd, 


IK 


cx.sn) 


ClnuaXd, 


IN 


V8S_PWSZ 


pwa zPKOvidexNaiui , 


I* 


V5S_PR0VIDER m T¥fe eProvidGrType , 


IN 


VSS FH3Z 




XN 
) 


vssjto 


Frov±d«£VBXBiom<l 



!VssAdmin::UnRegisterProvider() dereglsters the provider and removes it and any 
snapshots instantiated by the provider from snapshot management 

The Providerld is a GUID that uniquely and persistently identifies the Provider. 
For example the volsnap.sys provider is defined as: 

const CUID vs s_swpRV_Pr o vidarld « < Oxb5946l37, 0x7b9f , 0x4925, { Oxaf 
Ox80, 0x51, Ownto, 0xd6, 0«ti # 0x20, 0x03 } >; 

Once defined, the Providerld should remain the same; this Is true even when the 
software revision is updated. The only reason for changing a provider GUID is 
when the provider functionality changes and both providers might reasonably be 
active on the same system. 



IVssProviderCreateSnapshot: Creating Snapshots 

The iVssProviderCreateSnapshotSet Interface contains the methods used 
during snapshot creation. All providers must support this Interface; the Interface 
is common to software and hardware providers. 

For ail methods, a successful return Indicates that processing for any and ail LUNs 
In the snapshot set was successful. 

IVssPrvvlderCreAte£napshot::EnifPrepareSiiapshQt& 

This method win be called once for the complete snapshot set After this is called, 
there will be no more BeglnPrepareSnapshot calls. This method is intended as a 
rendezvous where the provider can watt for any snapshot preparation work to 
complete. 

B RESULT EndPrepare$napshots( 

[in) VSSJC0 Snapshot Set Id, 

Parameters 

SnapshotSetld 

fin J Snapshot set Identifier 

KVssPi^vidorCreateSnapshob:PraOommitSnapshots 
The PreCommitSnapshots method Is called prior to snapshot commit. It should 
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be used to prepare all snapshots in this Snapshots* for committing by the 
subsequent CommltSnapshotsQ method. While this is called, applications have 
been frozen (but the I/O subsystem is not yet blocking filesystem I/O) so the 
provider should attempt to minimize the amount of time spent In this method. 
h result Precemtit Snapshot 5 1 

tin] VS5_ID SnapshotScdd, 

) s 

SnapshotSettd 

[In] Snapshot set identifier. 

IVs«ProviderCreateSnapshot::CommitSnapshots 
The CommitSnapshots method is called at the defined instant at which the 
snapshots should be taken. For each prepared LUM in this snapshot set, the 
provider shall perform whatever work is appropriate in order to persist the point- 
in-time LUN contents, while this method Is called, both applications and the I/O 
subsystem are quiesced so the provider must attempt to minimize the amount of 
time spent in this method. As a general rule, a provider should spend less than 1 
second in this method. 

In addition, since the I/O system Is quiesced at this time, the provider shall take 
great care not to initiate any I/O that may deadlock the system - for example 
debug/tracing I/O by the method or by any methods It has Invoked (Note that 
VM-oriented file or paging I/O will not be frozen at this time). 

H RESULT Camrait Snapshot a ( 

[in] VSS_tI3 Sn*pshotSetl<l, 

) s 

Parameter 

SnapshotSeW 

[In] Snapshot set Identifier. 

IVssProvlderCraateSnapshotttPostCommitSnapsliots 
The PostCommitSnapshots method Is called after all providers Involved in the 
Snapshot set have succeeded with CommltSnapshots, and VSS has released the 
'Lovelace' lock on the system I/O. Note that applications are still frozen at this 
time. 

This method is an opportunity for the provider to provide additional cleanup work 
after the snapshot commit Note that lsnapghotcotmt should not be needed by 
hardware providers but is necessary for software providers. 

HHESOLT tostCCmnitSnapshots ( 

[inl vss^id snapahotsetio:, 
[in] LONG ISnapshotCaunt 

) t 
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Parameter* 

SnapshotSetld 

[in] Snapshot sec identifier. 

ISnapshotCount 

[in] Count of snapshots in the snapshot set, 
IVssProviderCroateSnapshot::AbortSnapshots 

The AbortSnapshots method aborts prepared snapshots in this provide. This 
Includes ail non-committed snapshots and pre-committed ones, 

H RESULT AbortSnapshots ( 

^ [in] vss_lD SnapshotSetld 

PaidtnetBrs 

SnapshotSetld 

[In] Snapshot set Identifier. 



IVssHardwareSnapshotProvlden Managing LUNs and 
Volumes 

The XVssHardwareSnapshotProvider interface contains the methods used by 
VSS to map volumes to LUNs, discover LUNs created during the snapshot 
process, and transport LUNs on a SAN. All hardware providers must support this 
interface. 

VD9.LUNJNFO 

VD$_LUNJNFO structure contains all hardware properties that can be used to 
locate a LUN. 

VSS initializes the fields from the SCSI OxOO # 0x80, and 0x83 commands for all 
LUNs that contribute to a snapshots set. The provider initializes any Interconnect 
specific addresses for any such LUNs and/or corrects any omissions. 

For all LUNs created by committing a snapshot, the provider Initializes all fields. 
This allows the newly created LUNs to be located by Windows software both on 
the original machine and/or any other machine In a SAN. 

typedef struct _vds_lun_inpo 
{ 

ULOng m_ver3ion; 

// The SCSI-2 device type 
BYTE ra._DeviceType; 

// The SCSI-2 device type modifier (if any) - this may be zero 
BYTE ra_Oevic©TypeHo<liCier; 
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// Flag indicating whether the device can support multiple 
// outstanding commands. The actual synchronization in this 
// case is tha responsibility of the port driver. 
BOOL mJ&ConrmandQueueing; 

// Contains the bus type (as defined above) of the device, it 
// should be used to interpret the raw device properties at 
// the end of this structure (if any) 
VDS_STORAG£_BU5_TYPE BusType ; 

// vendor id string. For devices with no such ID 
// this will bo zero 
[string) char *m_s z Vendor Id; 

// device«s product id string. For devices With no such ID 

// this will be zero 

tstring3 char *m_sz?xoductId; 

// zero-terminated ascii string containing the device's 

// produce revision String. Tor devices with, no such String 

// this will be zero 

[string] char *m_s*Product Revision; 

// zero-terminated ascii string containing the device's 
// serial number. For devices with no serial number 
// this will be zero 
[string] char *m_SZSerialNumber; 

// device id descriptor 

VT3S_STQRAGE_D£VICE_ID_D£SCRI PTOR m_device I descriptor; 

// number o£ interconnects 
ULONO clnter connects; 

// array of interconnects 

|size__is(clnterconnects) ] VDS^I INTERCONNECT *rglnterconnects; 
} VDS_LtJN_INFO,- 

typedef struct _VD$_INTERCONHECT 
i 

if address type 

VDS_IWTERCONNECT_ADDRESS_TYPB m_addressType; 
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// size of address 
ULONG m_chAddress; 

// address 

[siz«_istm_CbAddresaJ] BYTE -m_j>bAddress; 
} VOS_I INTERCONNECT; 

Notes: 

■ All disk or LUN identification structures are defined by the Virtual Disk 
Service (VDS). The Volume Snapshot Service and Fabric Visualization 
Service use these same definitions. 

• The VDS_STORAGE_DEvlCE_ID_DESCRlPTORS directly corresponds to 
the return from context page 0x83. 

. VDS_INTERCONN ECT_ADDRESS_TYPE is an enumeration of 

recognized interconnect addressing schemes and Includes, but Is not 
limited to, FCFS, FCPH, FCP3, MAC (iSCSI), and SCSI. 

iVssHardwarcSnapshotProvidoniAreLunsSupported 

This method will be calJed for each snapshot that is added to the snapshot set. 
Prior to Invoking this method, VSS determines the LUNs that contribute to the 
LUN. 



For a specific volume, each LUN can contribute only once; a specific LUN may 
contribute to multiple volumes. VSS does no tracking of LUNs. The same LUN will 
never appear more than once In a single call, but may reappear on subsequent 
calls. Consider the case of twosnapshot volumes: D: and 6:. O: is an extended 
volume contained on LUNS 1 and 2. E: is a simple volume contained on LUN 2. If 
both volumes are added to the same snapshot set, LUN 2 will appear on 
subsequent calls. 

Prior to returning success, the provider updates the VDS_LUN_JNFO structure 
with the LUN Interconnect address(es) and any additional information to ensure 
later recognition of the LUN. 

H RESULT AreLunaSuppcrtCd ( 

linj LONG XfcWiCount, 
[in, out, size^is CLLunCOunt:) ] 

VDS_LUN^IHFO *pLunIn formation 

) • 

Parameters 

ILunCount 
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[in} Number of LUNs contributing to this snapshot volume 
pLunlnfcrmation 

[in, out] Array of VDSjJJN.INFO for each LUN contributing to the 
snapshot volume. 

IVssHardware5napshotProvitfen:BeglnPrepare$napshot 

This method will be called for each snapshot that is added to the Snapshot set. 

H RESULT BegirtPsep^ r ©Snapshot [ 

[in I VSS_ID Snaps hot Set Id r 

tin) V 5S_ID Snapshotld, 
I i n ] LONG lLunCoun t , 

Lin, unique, ai*e_i* llLvftCount ) J 

VDSJt,UN_I«ro *r$Lunlntonti*tion 

) ; 

Pmm0tdf& 

SnapshotSetTct 

[in] Snapshot set identifier* 

Snapshotld 

[In] Name of the volume the snapshot is to be created on. 
ILunCOunt 

[in] Number of LUNs contributing to this snapshot volume 
rgLunlnformatton 

[in] Array of VD5_LUN_lNFO for each LUN contributing to the snapshot 
volume 

iVssHardwareSnapshDtProvideruGetTargotLuns 

This method will be called once after PostCommktSnapshots for the complete 
snapshot set. Identifying Information for each newly created LUN is returned to 
V5S. That Information must Include not only the device attributes (eg serial 
number), but also any and all network addresses. 

H RESULT GetTargetLuiiH ( 

[in] LONG iLunCcunt, 

vds_luk_info • rgsourceLuns , 

[out, size_is (lLunCOunt) ] 

VDS_LUH INFO *rgDestinationLun3 

); 

Paramotors 

ILunCQUnt 

[in] Number of LUNs contributing to this snapshot volume 
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rgSourceLuns 

tin) Array of VDSJ-UNJNFO for each LUN contributing to the snapshot 
volume snapshot set identifier. 

rgDesGnatfonLans 

[out] Array of VDSJ.UN JNFO for each new LUN created during snapshot 
processing. There Should be a one-to-one correspondence between each 
element of rgSourceLuns and rgPestinationLuns. 

IVssHanfwaroSrtapshotProvidercOnLunEmpty 

This method Is called whenever VSS determines that snapshot LUN contains no 
interesting data. All snapshots have been deleted (which also causes deletion of 
the volume). The LUN resources may be rectaimed by the provider and reused for 
another purpose, 

Note that OnLunEmpty is called on a best effort basis. VSS invokes the method 
ONLY when the LUN is guaranteed to be empty. There may be many cases where 
the LUN is empty but VSS is unable to detect this. An example or this case is 
when a snapshot UJN Is moved to a different host but not actually transported or 
imported by VSS. That LUN appears as any other LUN and volumes can be simply 
deleced via Disk Management without any notification of VSS. 

H RESULT OnLunEmpty < 

[in, unique] VDS_LUN_lNFO ^Information 

> ? 



plnformatlon 

[In] The VDSJ_UN JNFO for an empty LUN 



IVssHardwaroSnapshotProvideniLocateMins 

This method will be called once when a snapshot set Is transported between 
machines. The provider Is responsible for any unmasking at the hardware and any 
necessary switch zoning. VDSJJJN_JNFO passed to the provider Is exactly that 
received by VSS at GetTargetLuns. 

Immediately after this method completes, VSS will perform any host-based 
unmasking and Invoke IOCTL_Dl£K_FIND_NEW_DEVICES. This causes any 
exposed LUNs to be discovered by PNP. Note that host-based masking Is a post- 
whistler feature. 



CinJ long lLiincount, 

tin, unique, 3izc_ls (ILunCount) 1 

VDS_LtfN_I N FO + rgSourceliuna 
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